<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>lsearch</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_460">&nbsp;</a>NAME</h4><blockquote>
lsearch, lfind - linear search and update
</blockquote><h4><a name = "tag_000_007_461">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="search.h.html">search.h</a>&gt;

void *lsearch(const void *<i>key</i>, void *<i>base</i>, size_t *<i>nelp</i>, size_t <i>width</i>,
    int (*<i>compar</i>)(const void *, const void *));
void *lfind(const void *<i>key</i>, const void *<i>base</i>, size_t *<i>nelp</i>,
    size_t width, int (*<i>compar</i>)(const void *, const void *));
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_462">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>lsearch()</i>
function is a linear search routine.  It returns a pointer into a table
indicating where an entry may be found.  If the entry does not occur, it is
added at the end of the table.  The
<i>key</i>
argument points to the entry to be sought in the table.  The
<i>base</i>
argument points to the first element in the table.  The
<i>width</i>
argument is the size of an element in bytes.  The
<i>nelp</i>
argument points to an integer containing the current number of elements in the
table.  The integer to which
<i>nelp</i>
points is incremented if the entry is added to the table.  The
<i>compar</i>
argument points to a comparison function which the user must supply (.Fn strcmp ,
for example).  It is called with two arguments that point to the elements
being compared.  The function must return 0 if the elements are equal and
non-zero otherwise.
<p>
The
<i><a href="lfind.html">lfind()</a></i>
function is the same as
<i>lsearch()</i>
except that if the entry is not found, it is not added to the table.  Instead,
a null pointer is returned.
</blockquote><h4><a name = "tag_000_007_463">&nbsp;</a>RETURN VALUE</h4><blockquote>
If the searched for entry is found, both
<i>lsearch()</i>
and
<i><a href="lfind.html">lfind()</a></i>
return a pointer to it.  Otherwise,
<i><a href="lfind.html">lfind()</a></i>
returns a null pointer and
<i>lsearch()</i>
returns a pointer to the newly added element.
<p>
Both functions return a null pointer in case of error.
</blockquote><h4><a name = "tag_000_007_464">&nbsp;</a>ERRORS</h4><blockquote>
No errors are defined.
<br>
</blockquote><h4><a name = "tag_000_007_465">&nbsp;</a>EXAMPLES</h4><blockquote>
This fragment will read in less than or equal to TABSIZE
strings of length less than or equal to ELSIZE
and store them in a table, eliminating duplicates.
<pre>
<code>
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;search.h&gt;

#define TABSIZE 50
#define ELSIZE 120

 ...
    char line[ELSIZE], tab[TABSIZE][ELSIZE];
    size_t nel = 0;
    ...
    while (fgets(line, ELSIZE, stdin) != NULL &amp;&amp; nel &lt; TABSIZE)
        (void) lsearch(line, tab, &amp;nel,
            ELSIZE, (int (*)(const void *, const void *)) strcmp);
    ...
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_466">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The comparison function need not compare every byte, so arbitrary
data may be contained in the elements in addition to the values
being compared.
<p>
Undefined results can occur if there is not enough room in the table to
add a new item.
</blockquote><h4><a name = "tag_000_007_467">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_468">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="bsearch.html">bsearch()</a></i>,
<i><a href="hsearch.html">hsearch()</a></i>,
<i><a href="tsearch.html">tsearch()</a></i>,
<i><a href="search.h.html">&lt;search.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from Issue 1 of the SVID.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

